HDF_PARSE

The HDF_PARSE function recursively descends through an HDF4 file and creates an ordered hash containing object information and data.

Note: This function is not part of the standard HDF interface but is provided as a programming convenience. Its IDL source code is in the file hdf_parse.pro, located in the IDL lib directory.

Example

The following example shows how to parse a file and print the tags of the ordered hash:

File = FILEPATH('vattr_example.hdf', SUBDIR=['examples','data'])

Result = HDF_PARSE(File)

Result

IDL prints:

{

   "_NAME": "C:\\<etc.>\\vattr_example.hdf",

   "_TYPE": "GROUP",

   "_FILE": "C:\\<etc.>\\vattr_example.hdf",

   "_PATH": "/",

   "MetObs": {

       "_NAME": "MetObs",

       "_TYPE": "VDATA",

       "_FILE": "C:\\<etc.>\\vattr_example.hdf",

       "_PATH": "/",

       "_COUNT": 10,

       "_NFIELDS": 1,

       "_FIELD_NAMES": ["TempDP"],

       "TempDP": {

           "_NAME": "TempDP",

           "_TYPE": "VDATA_FIELD",

           "_FILE": "C:\\<etc.>\\vattr_example.hdf",

           "_PATH": "/MetObs",

           "_ORDER": 1,

           "_IDL_DATATYPE": "INT",

           "_DATA": "<unread>",

           "field_contents": {

               "_NAME": "field_contents",

               "_TYPE": "ATTRIBUTE",

               "_FILE": "C:\\<etc.>\\vattr_example.hdf",

               "_PATH": "/MetObs/TempDP",

               "_IDL_DATATYPE": "STRING",

               "_DATA": "Dew point temperature in degrees Celsius."

           }

       },

       "vdata_contents": {

           "_NAME": "vdata_contents",

           "_TYPE": "ATTRIBUTE",

           "_FILE": "C:\\<etc.>\\vattr_example.hdf",

           "_PATH": "/MetObs",

           "_IDL_DATATYPE": "STRING",

           "_DATA": "Ground station meteorological observations."

       },

       "num_stations": {

           "_NAME": "num_stations",

           "_TYPE": "ATTRIBUTE",

           "_FILE": "C:\\<etc.>\\vattr_example.hdf",

           "_PATH": "/MetObs",

           "_IDL_DATATYPE": "INT",

           "_DATA": [10]

       }

   },

   "vdata_contents": {

       "_NAME": "vdata_contents",

       "_TYPE": "VDATA",

       "_FILE": "C:\\<etc.>\\vattr_example.hdf",

       "_PATH": "/",

       "_COUNT": 1,

       "_NFIELDS": 1,

       "_FIELD_NAMES": ["VALUES"],

       "VALUES": {

           "_NAME": "VALUES",

           "_TYPE": "VDATA_FIELD",

           "_FILE": "C:\\<etc.>\\vattr_example.hdf",

           "_PATH": "/vdata_contents",

           "_ORDER": 43,

           "_IDL_DATATYPE": "BYTE",

           "_DATA": "<unread>

       }

   },

   "num_stations": {

       "_NAME": "num_stations",

       "_TYPE": "VDATA",

       "_FILE": "C:\\<etc.>\\vattr_example.hdf",

       "_PATH": "/",

       "_COUNT": 1,

       "_NFIELDS": 1,

       "_FIELD_NAMES": ["VALUES"],

       "VALUES": {

           "_NAME": "VALUES",

           "_TYPE": "VDATA_FIELD",

           "_FILE": "C:\\<etc.>\\vattr_example.hdf",

           "_PATH": "/num_stations",

           "_ORDER": 1,

           "_IDL_DATATYPE": "INT",

           "_DATA": "<unread>"

       }

   },

   "field_contents": {

       "_NAME": "field_contents",

       "_TYPE": "VDATA",

       "_FILE": "C:\\<etc.>\\vattr_example.hdf",

       "_PATH": "/",

       "_COUNT": 1,

       "_NFIELDS": 1,

       "_FIELD_NAMES": ["VALUES"],

       "VALUES": {

           "_NAME": "VALUES",

           "_TYPE": "VDATA_FIELD",

           "_FILE": "C:\\<etc.>\\vattr_example.hdf",

           "_PATH": "/field_contents",

           "_ORDER": 41,

           "_IDL_DATATYPE": "BYTE",

           "_DATA": "<unread>"

       }

   }

}

The next example uses the READ_DATA keyword and prints the contents of a VData field:

File = FILEPATH('vattr_example.hdf', SUBDIR=['examples','data'])

Result = HDF_PARSE(File, /READ_DATA)

Print, Result['num_stations', 'VALUES', '_DATA']

IDL prints:

10

Syntax

Result = HDF_PARSE(File, [/ READ_DATA])

Return Value

The Result is an ordered hash containing the parsed file. The tags in the hash depend upon the object type, as outlined in the tables below.

Tags common to all object types

Tag

Description

_NAME

Object name (or filename if at top level)

_TYPE

Object type, which can be any of the following: VGROUP, VDATA, VDATA_FIELD, SD,
IMAGE, ATTRIBUTE, ANNOTATION, or PALETTE

_FILE

The filename to which the object belongs

_PATH

The full path within the file to the object. If the object is at the root level of the file, then this field is set to '/'.

Tags associated with VGroups

All objects within the group will be added to the group's hash with their names as the keys.

Tags associated with VData

Tag

Description

_COUNT

The number of records in the data

_NFIELDS

The number of fields in the dataset

_FIELD_NAMES

A string array with the names of all fields within the VData. If there are no fields, this value is set to !NULL.

Fields within the VData will be added as fields to the ordered hash with the field names as the hash key names. See the next table for a description of the fields.

If the VData contains attributes or annotations, they will be added to the Vdata hash with the attribute or annotation names for the keys.

Tags associated with VData fields

Tag

Description

_ORDER

 The number of entries (the order) of the field

_IDL_DATATYPE

 String value corresponding to the IDL data type of the field values

_DATA

If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string <unread>.

If the field contains attributes, they will be added to the data field's hash with the attribute names for the keys.

Tags associated with Scientific Datasets (SDs)

Tag

Description

_NDIMENSIONS

Number of dimensions

_DIMENSIONS

Dimensions of the dataset

_IDL_DATATYPE

A string corresponding to the IDL data type of the dataset

_DATA

 If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string <unread>.

If the dataset contains attributes, they will be added to the dataset's hash, with the attribute names for the keys.

Tags associated with images

Tag

Description

_RASTER_TYPE

HDF4 contains three types of raster images:

  • GR - General Raster
  • 8BIT - 8-bit raster image (RIS8)
  • 24BIT - 24-bit raster image (RIS24)

_NDIMENSIONS

The number of dimensions in the image.

_DIMENSIONS

The image dimensions

_IDL_DATATYPE

String value corresponding to the IDL data type of the image.

_INTERLACE

An integer corresponding to the interlace mode of the image data. Possible values are:

  • 0: Pixel interlace
  • 1: Line interlace
  • 2: Component interlace

_DATA

 If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string <unread>.

If the image contains attributes, they will be added to the dataset's hash, with the attribute names for the keys.

Tags associated with attributes

Tag

Description

_IDL_DATATYPE

 A string corresponding to the IDL data type of the dataset

_DATA

The data from the attribute. The HDF_PARSE function always reads data from attributes, regardless of the READ_DATA keyword setting.

Tags associated with annotations

Tag

Description

_DATA

The value stored in the annotation. The HDF_PARSE function always reads data from annotations, regardless of the READ_DATA keyword setting.

Tags associated with palettes

Tag

Description

_DATA

 The value stored in the annotation. The HDF_PARSE function always reads data frompalettes, regardless of the READ_DATA keyword setting.

Arguments

File

A string that specifies the file to be parsed.

Keywords

READ_DATA

If you set this keyword, all data from scientific datasets, images, and VData fields will be read from the file. If you do not set this keyword, the _DATA field for these object types will be set to the string '<unread>'.

Version History

8.4.1

 Introduced

See Also

H5_PARSE